useBuyModal

Hook for managing the buy modal interface for collectible purchases

Import

import { useBuyModal } from "@0xsequence/marketplace-sdk/react";

Usage

Make sure you have followed the Getting Started guide to get the collection address and chainId.

Examples

Market Purchase

Example of implementing a market purchase (secondary sales) using the useBuyModal hook:

This example uses the useLowestListing hook from marketplace-sdk. If there is no lowestListing with the given parameters, it means there is no orderId available, and therefore the item cannot be bought.

1. Setup handler component with marketplace config validation

   First, create a main component that handles marketplace configuration loading and validation:

   import {
     useBuyModal,
     useLowestListing,
     useMarketplaceConfig,
   } from '@0xsequence/marketplace-sdk/react';
   import type { Address } from 'viem';
   
   function MarketPurchaseExample() {
     const { data: marketplaceConfig, isLoading: isMarketplaceConfigLoading } =
       useMarketplaceConfig();
   
     // Handle loading states
     if (isMarketplaceConfigLoading) {
       return <div style={{ padding: '20px' }}>Loading marketplace config...</div>;
     }
   
     if (!marketplaceConfig) {
       return (
         <div style={{ padding: '20px' }}>No marketplace config available</div>
       );
     }
   
     const collection = marketplaceConfig.market.collections[0];
   
     if (!collection) {
       return <div style={{ padding: '20px' }}>No collections available</div>;
     }
   
     const chainId = collection.chainId;
     const collectionAddress = collection.itemsAddress as Address;
   
     return (
       <MarketPurchase
         chainId={chainId}
         collectionAddress={collectionAddress}
         collectibleId="0"
       />
     );
   }
   
2. Create market purchase component

   Next, create the actual market purchase component that uses properly validated data:

   interface MarketPurchaseProps {
     chainId: number;
     collectionAddress: Address;
     collectibleId: string;
   }
   
   function MarketPurchase({
     chainId,
     collectionAddress,
     collectibleId,
   }: MarketPurchaseProps) {
     const {
       data: lowestListing,
       isLoading: isLoadingLowestListing,
       isError: isErrorLowestListing,
     } = useLowestListing({
       collectionAddress,
       chainId,
       tokenId: collectibleId,
     });
   
     const { show: showMarketModal } = useBuyModal({
       onSuccess: ({ hash, orderId }) => {
         console.log('Market purchase successful', { hash, orderId });
       },
       onError: (error) => {
         console.error('Market purchase failed:', error.message);
       },
     });
   
     const handleMarketBuy = () => {
       if (!lowestListing || isLoadingLowestListing) return;
   
       showMarketModal({
         chainId,
         collectionAddress,
         collectibleId,
         orderId: lowestListing.orderId,
         marketplace: lowestListing.marketplace,
       });
     };
   
     if (isLoadingLowestListing) {
       return <div style={{ padding: '20px' }}>Loading listing...</div>;
     }
   
     if (isErrorLowestListing || !lowestListing) {
       return (
         <div style={{ padding: '20px' }}>
           Error loading listing or no listing found
         </div>
       );
     }
   
     return (
       <div style={{ padding: '20px' }}>
         <h3>Market Purchase</h3>
   
         <p>Price: ${lowestListing.priceUSDFormatted}</p>
   
         <button
           type="button"
           onClick={handleMarketBuy}
           disabled={isLoadingLowestListing || isErrorLowestListing}
         >
           Buy from Market
         </button>
       </div>
     );
   }
   

Shop Purchase

Example of implementing a shop purchase (primary sales) using the useBuyModal hook:

This example uses the useListPrimarySaleItems hook from marketplace-sdk. The hook fetches primary sale items from a specific contract. If there is no primarySaleItem with the given parameters or if the supply is 0, the item cannot be bought.

1. Setup handler component with marketplace config validation

   First, create a main component that handles marketplace configuration loading and validation:

   import {
     useBuyModal,
     useListPrimarySaleItems,
     useMarketplaceConfig,
   } from '@0xsequence/marketplace-sdk/react';
   import type { Address } from 'viem';
   
   function ShopPurchaseExample() {
     const { data: marketplaceConfig, isLoading: isMarketplaceConfigLoading } =
       useMarketplaceConfig();
   
     // Handle loading states
     if (isMarketplaceConfigLoading) {
       return <div style={{ padding: '20px' }}>Loading marketplace config...</div>;
     }
   
     if (!marketplaceConfig) {
       return (
         <div style={{ padding: '20px' }}>No marketplace config available</div>
       );
     }
   
     const collection = marketplaceConfig.shop.collections[0];
   
     if (!collection) {
       return <div style={{ padding: '20px' }}>No shop collections available</div>;
     }
   
     const chainId = collection.chainId;
     const collectionAddress = collection.itemsAddress as Address;
     const saleContractAddress = collection.saleAddress as Address;
   
     return (
       <ShopPurchase
         chainId={chainId}
         collectionAddress={collectionAddress}
         saleContractAddress={saleContractAddress}
         collectibleId="0"
       />
     );
   }
   
2. Create shop purchase component

   Next, create the actual shop purchase component that uses properly validated data:

   interface ShopPurchaseProps {
     chainId: number;
     collectionAddress: Address;
     saleContractAddress: Address;
     collectibleId: string;
   }
   
   function ShopPurchase({
     chainId,
     collectionAddress,
     saleContractAddress,
     collectibleId,
   }: ShopPurchaseProps) {
     const { show: showBuyModal } = useBuyModal({
       onSuccess: ({ hash }) => {
         console.log('Shop purchase successful', { hash });
       },
       onError: (error) => {
         console.error('Shop purchase failed:', error.message);
       },
     });
   
     // Fetch primary sale items
     const { data: primarySaleItems, isLoading: isLoadingPrimarySale } = useListPrimarySaleItems({
       chainId,
       primarySaleContractAddress: saleContractAddress,
       filter: {
         includeEmpty: true,
       },
     });
   
     const primarySaleItem =
       primarySaleItems?.pages[0]?.primarySaleItems[0]?.primarySaleItem;
   
     const handleShopBuy = () => {
       if (!primarySaleItem) return;
   
       showBuyModal({
         chainId,
         collectionAddress,
         salesContractAddress: saleContractAddress,
         cardType: 'shop',
         quantityDecimals: 0,
         quantityRemaining: Number(primarySaleItem.supply),
         items: [
           {
             tokenId: collectibleId,
             quantity: '1',
           },
         ],
         salePrice: {
           amount: primarySaleItem.priceAmount ?? '0',
           currencyAddress: (primarySaleItem.currencyAddress as Address) ?? '0x',
         },
       });
     };
   
     if (isLoadingPrimarySale) {
       return <div style={{ padding: '20px' }}>Loading primary sale items...</div>;
     }
   
     if (!primarySaleItem) {
       return (
         <div style={{ padding: '20px' }}>No primary sale items available</div>
       );
     }
   
     return (
       <div style={{ padding: '20px' }}>
         <h3>Shop Purchase</h3>
   
         <p>Available: {primarySaleItem.supply ?? 0}</p>
   
         <button
           type="button"
           onClick={handleShopBuy}
           disabled={!primarySaleItem || Number(primarySaleItem.supply) === 0}
         >
           Buy from Shop
         </button>
       </div>
     );
   }
   

Parameters

The hook accepts an optional callbacks object with the following properties:

interface ModalCallbacks {
  onSuccess?: ({ hash, orderId }: { hash?: Hash; orderId?: string }) => void;
  onError?: (error: Error) => void;
  successActionButtons?: Array<{ label: string; action: () => void }>;
}

Parameter	Type	Description
callbacks.onSuccess	({ hash, orderId }: { hash?: Hash; orderId?: string }) => void	Optional callback function called when the purchase is successful
callbacks.onError	(error: Error) => void	Optional callback function called when an error occurs during the purchase
callbacks.successActionButtons	Array<{ label: string; action: () => void }>	Optional array of action buttons to show on success

Return Type

The hook returns an object with the following methods:

{
  show: (args: BuyModalProps) => void
  close: () => void
}

Methods

show

(args: BuyModalProps) => void

Opens the buy modal with the specified parameters. The BuyModalProps can be either ShopBuyModalProps or MarketplaceBuyModalProps depending on the purchase type.

For market purchases (Secondary sales):

interface MarketplaceBuyModalProps extends BuyModalBaseProps {
  marketplaceType?: "market";
  collectibleId: string;
  marketplace: MarketplaceKind;
  orderId: string;
}

For shop purchases (Primary sales):

interface ShopBuyModalProps extends BuyModalBaseProps {
  marketplaceType: "shop";
  salesContractAddress: Address;
  items: Array<Partial<CheckoutOptionsItem> & { tokenId?: string }>;
  quantityDecimals: number;
  quantityRemaining: number;
  salePrice: {
    amount: string;
    currencyAddress: Address;
  };
  unlimitedSupply?: boolean;
}

Both types extend from BuyModalBaseProps:

interface BuyModalBaseProps {
  chainId: number;
  collectionAddress: Address;
  skipNativeBalanceCheck?: boolean;
  nativeTokenAddress?: Address;
  marketplaceType?: MarketplaceType;
  customCreditCardProviderCallback?: (buyStep: Step) => void;
  successActionButtons?: Array<{ label: string; action: () => void }>;
}

close

() => void

Closes the buy modal.

Notes

The useBuyModal hook provides a convenient way to manage the buy modal interface for collectible purchases. It handles:

• Opening and closing the modal
• Managing the purchase flow state
• Error handling and success callbacks
• Support for both primary and secondary sales